/----------------------------------------------------------------------------\
|                 6502/65C02 Turbo Assembler specification                   |
|                      (c)1997 by Taboo Productions!                         |
|                               Version 1.31                                 |
\----------------------------------------------------------------------------/

1. Introduction
===============

   The 6502/65C02 Turbo Assembler is designed for all 8-bit computers with
processor compatible with 6502/65C02 (for example Commodore or Atari
computers). It is 100% compatible with Commodore 64's TASS v5.1 and the most
of its further releases.
The registered version contains furthermore the whole lot of extra
capabilities like macros, for..next or if..else constructions, and much more.

2. Copyright
============

The shareware version can be freely distributed without any limits and can be
used for all non-commercial applications (like demos, or any other freeware
programs) which you don't get royalties for, however it's nicely welcome if
you register this program even for non commercial purposes.
The registered version can be used by one programmer (or one programming-team)
in all applications.
It is illegal to sell the Turbo Assembler itself, doesn't matter if you have
shareware or registered version.
The features of TASS which are not available in the shareware version are
marked with (*) in this manual.

3. Usage/Command Line
=====================

Syntax:  TASS [options] <source> [object] [listing](*)

If there's no extension in <source> file, '.TAS' is added automatically.
If you don't type object file's name, Tass will assume the name of source
with extension '.O64' or '.N64' when you select nonlinear output file format
(see below).
The listing file's standard extension is 'L64'.

You are allowed to type following switches as options:
/n - select nonlinear output file format. It produces the output binary
     object file in a different way, containing:
     1 word - number of bytes in 1st block
     1 word - address of the 1st block
     1st binary block of data
     1 word - number of bytes in 2nd block (0 = end of file)
     1 word - address of the 2nd block
     2nd binary block of data
     ...
     Warning! The nonlinear output file cannot be used with TSLINK!
/w - ignore all warning messages
/c - allow 65C02 mnemonics and operands(*)
/a - convert ASCII to PETASCII in texts typed with .byte and .text commands
     and quoted values
/m - don't put monitor-alike code into listing(*)
/s - don't put source code into listing(*)
/l<name> - generate a file with all labels used in the source

4. Commands
===========

ͻ
.byte <expr1>,<expr2>,...
.text <expr1>,<expr2>,...
ͼ
  Put bytes directly into the memory. Each <expression> can be replaced with
  quoted text.
  If an expression is preceded with ^-sign its value will be converted into
  string and put to the memory as an ASCII string.
  .byte and .text do exactly the same and are distinguished only for
  compatibility with C64's TASS.

ͻ
.word <expr1>,<expr2>,...
ͼ
  Puts words into the memory.

ͻ
.offs <bytes_to_skip>
ͼ
  Increases the physical address by <bytes_to_skip>. The logical address is
  not changed. It's implemented for compatibility but there's no sense to use
  it any longer (compare commands .logical and .here below)

ͻ
<macro_name> .macro(*)
...                
.endm              
ͼ
  Generates a macro named <macro_name>. You can execute the macro afterwards
  with:
#<macro_name> <param1>,<param2>,...
  The parameters are available inside the macro with variables \1,\2,...,\9
  and \a,\b,...,\z. If you wish to put comma inside the parameter, you have to
  quote it.
  If the unquoted param is preceded with ^-sign, the parameter will be the
  number-value of the expression and not the expression itself.

ͻ
.for <init_assignment>,<expression>,<loop_assignment>(*)
...                                                  
.next                                                
ͼ
  Let's you repeat a part of source. The <init_assignment> must be in form
  <variable>=<expression> and is executed when the .for starts.
  <expression> is checked everytime _before_ the source between .for and
  .next is being processed (only when <expression> doesn't equal 0).
  <loop_assignment> must be in form <variable>=<expression> and is being
  processed when .next is found.
  The init and loop assignments can be skipped when not needed.

ͻ           ͻ
.if <expression>(*)  or    .if <expression>(*)
...                        ...             
.else                      .fi             
...                        ͼ
.fi             
ͼ
  Processes a part of source between .if and .else (or .if and .fi when .else
  is skipped) only when <expression> doesn't equal 0. The source between
  .else and .fi is being processed otherwise.

ͻ
.rept <rept_count>(*)
...               
.next             
ͼ
  Processes the source between .rept and .next <rept_count> times. There's no
  repeat-counter available.

ͻ
.include <tass_file>(*)
ͼ
  Includes other source to the source. All labels are global and must be
  unique in both sources.

ͻ
.binary <binary_file>(*)
ͼ
  Includes a file as binary.

ͻ
.comment(*)
...     
.endc   
ͼ
  Ignores the source between .comment and .endc.

ͻ
.page(*)
...  
.endp
ͼ
  Checks the high-bytes of the addresses, where .page and .endp are found.
  When different, reports an error.

ͻ
.logical <address>(*)
ͼ
  Sets the logical address to <address>. It's useful when you want the
  program to be executed afterwards in other memory region than it's being
  assembled.

ͻ
.here(*)
ͼ
  Sets the logical address the same number of bytes after physical address
  as it was before _the last_ .logical command.
  The .logical and .here commands can be nested.

5. Operators (in order of precedence)
=====================================

ͻ
symbol    name          args bind                  note                 
͹
  +   plus sign          1    r    Does nothing                         
  -   negation           1    r                                         
  !   logical negation   1    r    Returns 1 if arg=0, otherwise 0      
Ķ
  >>  right bit-shift    2    l                                         
  <<  left bit-shift     2    l                                         
Ķ
  &   logical and        2    l                                         
Ķ
  |   logical or         2    l                                         
  ^   logical xor        2    l                                         
Ķ
  *   multiplication     2    l                                         
  /   division           2    l                                         
  //  modulus            2    l                                         
Ķ
  +   addition           2    l                                         
  -   substraction       2    l                                         
Ķ
  =   equal              2    l    \                                    
  !=  not equal          2    l     |                                   
  >   greater            2    l     > returns 1 if true, otherwise 0    
  <   less               2    l     |                                   
  >=  greater or equal   2    l     |                                   
  <=  less or equal      2    l    /                                    
Ķ
  <   low byte           1    r                                         
  >   high byte          1    r                                         
ͼ

Note:
  The 'args' defines how many arguments needs the operator.
  'bind' defined the direction (left or right) of counting the expression
  at operators of the same priority.

  Note that some of the operators have two meanings depending on the place,
  they are used. Anyway, you must be very careful using complicated
  expressions. For example 1<<3 will be treated as "1 shifted left by 3 bits",
  but 1< <3 will be treated as "1 is less than low byte of 3".

  There's moreover no difference between the assignment-sign (=) and the
  operator "equal" (=). For example line: a=b=0 won't assign 0 to b and
  a, but will compare b to 0 and the result will be assigned to a.

  The assignment-sign (=) defines a variable. If you want to define a constant
  use := instead. This will prevent getting unexpected warning 'Using variable
  before declaration' when you use the value as an operand even before the
  declaration of the constant (which can be sometimes correct).

  Each expression can be preceded with @b or @w. @b forces the expression to
  be treated as byte even when the value of the expression is not known yet
  (forward references). @w forces the expression to be treated as word even
  if it's less than $100.

6. Numbers
==========

All numbers are normally decimal, however you can use hexadecimal numbers
preceded with $ sign as well as binary numbers preceded with % sign.
Furthermore 1-byte values can be written as ascii codes when you have them
quoted.

7. Constants
============

User defined, written in an empty line or before mnemonic or command (except
.macro). The constant is assigned the logical address value and it's not
allowed to change or redefine it afterwards.

\1,\2,...,\9,\a,\b,...,\z are macro params and it's illegal to use them
  ouside a macro.(*)

8. Variables
============

User defined, long, signed values between -$80000000 and $7fffffff. You can
change it anywhere since not defined as a constant. If you want to have it
assigned the logical address, type: <variable>=* or <variable>:=*
All identifiers are case-nonsensitive!

* : when set: sets both physical and logical address.
    when read: returns logical address.

9. Assembly errors
==================

ͻ
Double defined               you have declared a variable which has been   
                             already defined as constant or a constant     
                             which has been already declared as constant   
                             or variable.                                  
Ķ
Not defined                  You are using a label which hasn't been       
                             defined or is a forward reference when it     
                             cannot be.                                    
Ķ
Extra characters on line     There are some extra characters on line       
                             assembler doesn't expect.                     
Ķ
Constant too large           You typed a number which is greater than      
                             $7fffffff or an address which is greater than 
                             $ffff or a byte greater than $ff.             
Ķ
General syntax               Assembler can't process a line because of     
                             it's nonsense.                                
Ķ
... expected                 Assembler expects a concrete sign or command. 
Ķ
Expression syntax            There's an error in the expression, for       
                             example you have badly used an operator or    
                             didn't close all brackets.                    
Ķ
Branch too far               The relative jump has been too long.          
Ķ
Missing argument             Assembler expects more arguments in specified 
                             command.                                      
Ķ
Can't locate file            There's no way to access source or binary     
                             file.                                         
Ķ
Out of memory                There's no memory for labels or macros.       
Ķ
Can't write object file      There's an error while writing object file.   
Ķ
Line too long                The line was longer than 256 characters.      
Ķ
Reserved word used as symbol You have used reserved word (mnemonic) as     
                             a label.                                      
Ķ
Illegal operand              You have used illegal operand to the mnemonic 
Ķ
Can't write listing file     There's an error while writing listing file.  
Ķ
Page error at $addr          .page and .endp are placed on different       
                             memory pages.                                 
Ķ
Can't write label file       There's an error while writing label file.    
Ķ
Too many errors              There was more than 100 errors.               
ͼ

10. Assembly warnings
=====================

ͻ
Using variable before declaration You are using a variable which is defined
                                  afterwards.                              
Ķ
Possibly incorrectly used A       Tass 5.1 treated symbol 'a' after        
                                  mnemonics asl, lsr, rol, ror as an       
                                  accumulator but if you are using variable
                                  'a' there's a possibility that you want  
                                  _it_ to be the operand. If you do,       
                                  you must have it in brackets.            
Ķ
Top of memory exceeded            Compiled program exceeded address $ffff  
ͼ

11. How to register
===================

- if you live in Poland:
  Wplac 10PLN na konto nr 10202313-450805-270-41-111
  w banku PKO BP I/O Katowice, ul. Warszawska 12.
  Uruchom tass.exe ze switch'em /r i postepuj zgodnie z instrukcja.
- if you don't:
  Send $10 (or more :-) to the address below:
  Marek Matula
  Ligocka 2/36
  40-570 Katowice
  Poland

  After that you should run tass.exe with the switch /r and follow the
  instructions.
  If you have email let me know and I will inform you where to find the
  further releases of 6502 TASS.
  Feel free to give me any suggestions at:  marekm@zeus.polsl.gliwice.pl
  The newest version of 6502 Tass can be always found on Taboo Home Page:
  http://taboo.eu.org/download/

--- end of file ---
